Create subscription transition

Transition a subscription to another subscription, configured from a subscription, a plan or a template. If the application_schedule is immediately, the transition is applied right away.

POST /v2/subscriptions/transitions

Create subscription transition

cURL

curl --request POST \
  --url https://api.hyperline.co/v2/subscriptions/transitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source_subscription_id": "<string>",
  "target_subscription": {
    "phases": [
      {
        "activation_strategy": "manual",
        "end_strategy": "duration",
        "billing_date_setting": "phase_start",
        "products": [
          {
            "id": "itm_FJKlqUb8COXw55",
            "name": "Product name",
            "description": "A description of the product.",
            "description_display_interval_dates": false,
            "payment_interval": {
              "period": "once"
            },
            "payment_schedule": "start",
            "price": {
              "type": "fee",
              "amount": 200
            },
            "prices": [
              {
                "type": "volume",
                "from": 0,
                "to": 20,
                "amount": 200,
                "unit_count": 1,
                "on_tier_incomplete": null
              },
              {
                "type": "volume",
                "from": 20,
                "to": null,
                "amount": 150,
                "unit_count": 1,
                "on_tier_incomplete": null
              }
            ],
            "count": 2,
            "unit_name": "user",
            "min_committed_count": 2,
            "min_amount": 123,
            "max_amount": 123,
            "bill_usage_difference": false,
            "credits_expiration_in_days": 123,
            "expire_credits_at_end_of_period": false
          }
        ],
        "name": "Name of the subscription phase.",
        "type": "standard",
        "status": "pending",
        "order": 0,
        "duration": {
          "count": 1,
          "period": "years"
        },
        "initial_billing_at": "2024-12-20T16:04:11Z",
        "starts_at": "2024-12-20T16:04:11Z",
        "ends_at": "2024-12-20T16:04:11Z",
        "billing_cycle_alignment": "anniversary",
        "do_not_invoice_phase": false,
        "transition_calculation_method": "prorata",
        "transition_invoicing_schedule": "immediately",
        "coupons": [
          {
            "id": "<string>",
            "duration_count": 123,
            "expires_at": "2024-12-20T16:04:11Z",
            "apply_at": "2024-12-20T16:04:11Z",
            "product_ids": [
              "<string>"
            ]
          }
        ]
      }
    ],
    "name": "<string>",
    "purchase_order": "<string>",
    "invoicing_entity_id": "ive_jerrb484RHn",
    "crm_opportunity_id": "<string>",
    "commitment_interval": {
      "period": "years",
      "count": 1
    },
    "renew_for": {
      "period": "years",
      "count": 1
    },
    "minimum_invoice_fee": 250,
    "starts_at": "2024-12-20T16:04:11Z",
    "contract_start": "2024-01-15T00:00:00Z",
    "contract_end": "2025-01-15T00:00:00Z",
    "initial_billing_at": "2024-12-20T16:04:11Z",
    "display_shipping_details": true,
    "cancel_at": "2024-12-20T16:04:11Z",
    "cancellation_amount": 123,
    "properties": {},
    "custom_properties": {},
    "tax_only": true,
    "generate_draft_invoices": true,
    "generate_document": true,
    "document_name": "<string>",
    "add_tax_to_document": true,
    "do_not_charge_subscription": true,
    "invoice_custom_note": "<string>",
    "plan_id": "plan_zHmjoDee4ZRmQV",
    "template_id": "subt_7gdusOkqr5L0B8",
    "template_configuration_id": "subtc_7mHWOlPStUogvp"
  },
  "name": "<string>",
  "transition_date": "2024-12-20T16:04:11Z"
}
'

200

{
  "id": "<string>",
  "customer_id": "<string>",
  "base_subscription_id": "<string>",
  "source_subscription_id": "<string>",
  "target_subscription_id": "<string>",
  "transitioned_at": "2023-12-25",
  "name": "<string>",
  "transition_date": "2023-12-25"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

source_subscription_id · string · required

The ID of the subscription to transition from

application_schedule · enum<string> · required

Whether the transition should be applied 'immediately' or 'scheduled' for a specific date. Past dates within the current billing period are supported and will be applied immediately.

Available options: scheduled, immediately

target_subscription · With phases · object · required

The configuration of the subscription to transition to

With phases

Without phases

Show child attributes

name · string

An optional name for the transition

calculation_method · enum<string>

The calculation method to use for the transition. 'do_not_charge' will not generate any transition invoice. 'pro_rata' will generate a prorated invoice for the remaining period.

Available options: do_not_charge, pro_rata

billing_cycle_transition_method · enum<string>

The billing cycle transition method to use. 'keep_current_billing_cycle' will keep the current billing cycle dates if possible. 'align_to_new_billing_cycle' will align the billing cycle to the transition date.

Available options: keep_current_billing_cycle, align_to_new_billing_cycle

transition_date · string<date-time>

The date at which the transition should occur. Only applicable if the application schedule is 'scheduled'. Can be a past date within the current billing period. UTC date time string in the ISO 8601 format.

Example:

"2024-12-20T16:04:11Z"

Response

200 - application/json

id · string · required

The unique identifier of the subscription transition

customer_id · string · required

The ID of the customer associated with the transition

base_subscription_id · string · required

The ID of the original subscription from which this transition is derived. It references the last active version of the subscription.

source_subscription_id · string · required

The ID of the subscription to transition from

target_subscription_id · string | null · required

The ID of the subscription to transition to

status · enum<string> · required

The current status of the subscription transition. Possible values are 'scheduled', 'completed', 'failed', and 'draft'.

Available options: scheduled, completed, failed, draft, cancelled, pending_quote_signature

transitioned_at · string<date> | null · required

The date and time when the transition was completed. Null if the transition is not yet completed. UTC date time string in the ISO 8601 format.

name · string | null · required

An optional name for the transition

transition_date · string<date> | null · required

The date at which the transition should occur. Only applicable if the application schedule is 'scheduled'. Can be a past date within the current billing period. UTC date time string in the ISO 8601 format.

application_schedule · enum<string> · required

Whether the transition should be applied 'immediately' or 'scheduled' for a specific date. Past dates within the current billing period are supported and will be applied immediately.

Available options: immediately, scheduled, next_renewal, quote_signature, scheduled_after_quote_signature

billing_cycle_transition_method · enum<string> | null · required

The billing cycle transition method to use. 'keep_current_billing_cycle' will keep the current billing cycle dates if possible. 'align_to_new_billing_cycle' will align the billing cycle to the transition date.

Available options: keep_current_billing_cycle, align_to_new_billing_cycle

calculation_method · enum<string> | null · required

The calculation method to use for the transition. 'do_not_charge' will not generate any transition invoice. 'pro_rata' will generate a prorated invoice for the remaining period.

Available options: do_not_charge, pro_rata